\chapter{HTTP API Standards}

\section{Hypermedia API's}

It would be irresponsible to cover HTTP-based API design without mentioning Hypermedia/\href{http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm}{REST (Representational State Transfer)} \cite{REST}. Hypermedia APIs may very-well be the future of HTTP API design. It really is an amazing concept, going \emph{back to the roots} of how HTTP (and HTML) was intended to work.

With the examples we've been covering until this point, the URL Endpoints are part of the contract between the API and the Consumer. These Endpoints must be known by the Consumer ahead of time, and changing them means the Consumer is no longer able to communicate with the API.

API Consumers are far from being the only user agent making HTTP requests on the Internet. Humans with their web browsers are the most common user agent making HTTP requests. Humans of course are \emph{not} locked into this predefined Endpoint URL contract that most HTTP APIs are.

What makes us humans so special? We're able to read content, click links for headings which look interesting, and in general explore a website and interpret content to get where we want to go. If a URL changes, we're not affected (unless we bookmarked a page, in which case we go to the homepage and find a new route to our beloved article).

The Hypermedia API concept works the same way a human would. Requesting the Root of the API returns a listing of URLs which point perhaps to each collection of information, and describing each collection in a way which the Consumer can understand. Providing IDs for each resource isn't important as long as a URL to the resource is provided.

With the Consumer of a Hypermedia API crawling links and gathering information, URLs are always up-to-date within responses and do not need to be known as part of a contract. If a URL is ever cached, and a subsequent request returns a 404, the Consumer can simply go back to the root and discover the content again.

When retrieving a list of Resources within a Collection, an attribute containing a complete URL for the individual Resources are returned. When performing a POST/PATCH/PUT, the response could be a \textbf{3XX} redirect to the complete resource.

JSON doesn't quite give us the semantics we need for specifying which attributes are URLs, nor how URLs relate to the current document (although, as we'll soon see, there are some standards for doing this). HTML, as you should already know, does provide this information! We may very well see our APIs come full circle and return to consuming HTML. Considering how far we've come with CSS, one day it may be common practice for APIs and Websites to use the exact same URLs and HTML content.

Imagine a tool on the internet that you want to use. It could be Google Calendar, or Meetup, or Facebook Events. Also imagine that you want to use other tools too, like email or instant messengers. Normally, integrations between tools are only convenient if you're using a massive suite of tools, such as what is offered by Microsoft or Google. As an example, Google Mail integrates very tightly with Google Calendar and Google+ to provide a seamless user experience.

Now, imagine that these disparate tools by different companies can work with each other as tightly as these massive suites of tools. Often times when a company builds a single product it is better than the equivalent component of a larger suite. This combination of specific, well-built tools working seamlessly with other services becomes the best of both worlds! The process could theoretically work automatically, with the different services discovering each other and configuring themselves to play nicely. This is a future offered by hypermedia-based APIs.

\subsection{ATOM: An Early Hypermedia API}

\href{https://en.wikipedia.org/wiki/Atom\_\%28standard\%29}{ATOM} \cite{HYPERATOM}, a distant cousin of RSS, is likely one of the first mainstream Hypermedia APIs (except for HTML itself). ATOM is valid XML, and therefore easy to parse. Links to other documents use a \texttt{link} tag, and specify both the URL (using the \texttt{href} attribute), as well as the documents relation to the current document (using the \texttt{rel} attribute).

\begin{verbatim}
<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <title>Example Feed</title>
  <subtitle>A subtitle.</subtitle>
  <link href="http://example.org/feed/" rel="self" />
  <link href="http://example.org/" />
  <id>urn:uuid:60a76c80-d399-11d9-b91C-0003939e0af6</id>
  <updated>2003-12-13T18:30:02Z</updated>
  <entry>
    <title>Atom-Powered Robots Run Amok</title>
    <link href="http://example.org/2003/12/13/atom03" />
    <link rel="alternate" type="text/html"
        href="http://example.org/2003/12/13/atom03.html"/>
    <link rel="edit"
        href="http://example.org/2003/12/13/atom03/edit"/>
    <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
    <updated>2003-12-13T18:30:02Z</updated>
    <summary>Some text.</summary>
      <author>
        <name>John Doe</name>
        <email>johndoe@example.com</email>
      </author>
  </entry>
</feed>
\end{verbatim}


\section{Response Document Standards}

When responding with a document representing, say, a Collection, it is usually adequate to return a top-level array containing each resource object. Likewise, when responding with a document representing a resource, simply returning a top-level object containing the resource is usually good-enough.

However, there are some standards which forward-thinking API Architects have developed for encapsulating these objects in a standardized envelope. These envelopes give the Consumer context when parsing the responses.

For example, if making a filtered request limits a Collection response to contain only 10 Resources, how do you let the Consumer know how many total records exist? How do you convey expected data types programmatically? These different response document standards provide methods for returning this meta data.

\subsection{JSON Schema}

\href{http://json-schema.org/}{JSON Schema} \cite{JSONSCHEMA} provides a method for describing the attributes provided by a API endpoints. This description is written in JSON in such a way as to be both human-readable and easy to work with programmatically. Using JSON Schema, a Consumer could easily automate data validation and generation of CRUD forms.

\subsubsection{Example JSON Schema Document}

\begin{verbatim}
{
  "title": "Example Schema",
  "type": "object",
  "properties": {
    "firstName": {
      "type": "string"
    },
    "lastName": {
      "type": "string"
    },
    "age": {
      "description": "Age in years",
      "type": "integer",
      "minimum": 0
    }
  },
  "required": ["firstName", "lastName"]
}
\end{verbatim}

\subsection{JSON API}

The \href{http://jsonapi.org/}{JSON API} \cite{JSONAPI} spec provided a standardized format for structuring response documents by introducing some reserved attributes which have special meaning (e.g. \texttt{id} must be used for identifying a resource, a convention we've been otherwise following).

An notable feature of JSON API is that is also provides a method for returning not only a requested resource but also other resources which it depends on, as if anticipating the Consumers next request(s).

\subsubsection{Example JSON API Document}

\begin{verbatim}
{
  "links": {
    "posts.author": {
      "href": "http://example.com/people/{posts.author}",
      "type": "people"
    },
    "posts.comments": {
      "href": "http://example.com/comments/{posts.comments}",
      "type": "comments"
    }
  },
  "posts": [{
    "id": "1",
    "title": "Rails is Omakase",
    "links": {
      "author": "9",
      "comments": [ "1", "2" ]
    }
  }],
  "linked": {
    "people": [{
      "id": "9",
      "name": "@d2h"
    }],
    "comments": [{
      "id": "1",
      "body": "Mmmmmakase"
    }, {
      "id": "2",
      "body": "I prefer unagi"
    }]
  }
}
\end{verbatim}

\subsection{Siren}

The \href{http://sirenspec.org}{Siren Hypermedia} \cite{SIREN} spec provides a standard method for representing resources and what actions can be performed on said resources. It is a Hypermedia API so the URL for performing an action or linking to a Resource is provided within the document.

\subsubsection{Example Siren Document}

\begin{verbatim}
{
  "class": [ "order" ],
  "properties": { 
      "orderNumber": 42, 
      "itemCount": 3,
      "status": "pending"
  },
  "entities": [
    { 
      "class": [ "items", "collection" ], 
      "rel": [ "http://x.io/rels/order-items" ], 
      "href": "http://api.x.io/orders/42/items"
    },
    {
      "class": [ "info", "customer" ],
      "rel": [ "http://x.io/rels/customer" ], 
      "properties": { 
        "customerId": "pj123",
        "name": "Peter Joseph"
      },
      "links": [ {"rel":["self"],
        "href":"http://api.x.io/customers/pj123"} ]
    }
  ],
  "actions": [
    {
      "name": "add-item",
      "title": "Add Item",
      "method": "POST",
      "href": "http://api.x.io/orders/42/items",
      "type": "application/x-www-form-urlencoded",
      "fields": [
        {"name":"orderNumber","type":"hidden","value":"42"},
        { "name": "productCode", "type": "text" },
        { "name": "quantity", "type": "number" }
      ]
    }
  ],
  "links": [
    { "rel": [ "self" ], "href":"http://api.x.io/orders/42"},
    {"rel":["previous"],"href":"http://api.x.io/orders/41"},
    { "rel": [ "next" ],"href": "http://api.x.io/orders/43"}
  ]
}
\end{verbatim}


\section{Alternatives to URL-based API's}

Up until now, we've placed a large emphasis on the importance of a URL in our HTTP-based API's. However, there are some standards you should be aware of which have a small emphasis on the URL, typically serving all requests through a single URL.

\subsection{JSON RPC}

\href{http://www.jsonrpc.org/specification}{JSON RPC} \cite{JSONRPC} is a relatively popular alternative to REST for exposing functionality over a network. Whereas REST is required to be accessed via HTTP, JSON RPC doesn't have a protocol requirement. It can be sent over sockets, be used with Inter Process Communication (IPC), and of course, HTTP.

Unlike REST which requires an abstraction of Server business-logic and data into simple objects which can be acted upon using CRUD, JSON RPC calls will typically map to existing functions within your application.

When a client makes a call using JSON RPC, they specify the name of a function to execute, as well as arguments to the function. Arguments can be in the form of either ordered parameters (using a JSON Array), or named parameters (using a JSON Object).

The important part of the specification is the envelope which the data adheres to. The concept of a URL doesn't really exist (if you're using JSON RPC over HTTP, there's usually a single URL which all requests are sent through, and each request is likely sent as a POST).

JSON RPC is mostly useful for situations where you don't have an HTTP server, for example multiplayer games or embedded systems or simple communication applications. If you already have an HTTP Server for your product or service, REST is likely a better solution for you.

With HTTP, every Request and Response is guaranteed to be paired together correctly. Due to the asynchronous nature of sockets and other such communication protocols, Requests need to provide a unique ID value, and the corresponding Response needs to provide the same ID.

JSON RPC also has mechanisms for sending batches of operations at once, and in some situations can compliment a RESTful API.

\subsubsection{Example JSON RPC Request}

\begin{verbatim}
{"jsonrpc":"2.0","method":"subtract","params":[42,23],"id":1}
\end{verbatim}

\subsubsection{Example JSON RPC Response}

\begin{verbatim}
{"jsonrpc": "2.0", "result": 19, "id": 1}
\end{verbatim}


\subsection{SOAP}

Worth mentioning is \href{https://en.wikipedia.org/wiki/SOAP}{Simple Object Access Protocol (SOAP)} \cite{SOAP}, which is a term you've very likely heard of. SOAP is a sort of successor to an older technology called \href{https://en.wikipedia.org/wiki/XML-RPC}{XML RPC}. As you've probably guessed, XML RPC is similar to JSON RPC, as both are forms of Remote Procedure Call protocols.

SOAP is useful for describing services exposed over the network, and is transport agnostic just like JSON RPC, although most implementations use it over HTTP. Partly due to the waning popularity of XML in comparison to JSON, SOAP is often looked down upon due to the verbosity and the bulkiness of document sizes.

SOAP is mostly used in larger corporate environments.

\subsubsection{Example SOAP Request}

\begin{verbatim}
<?xml version="1.0"?>
<soap:Envelope
    xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
  <soap:Header>
  </soap:Header>
  <soap:Body>
    <m:GetStockPrice xmlns:m="http://www.example.org/stock">
      <m:StockName>IBM</m:StockName>
    </m:GetStockPrice>
  </soap:Body>
</soap:Envelope>
\end{verbatim}
